Skip to content

Complete Cloudflare geo and add pinned Spin KV lookup - #514

Draft
prk-Jr wants to merge 5 commits into
feature/kv-geoipfrom
feature/480-cloudflare-spin-geo
Draft

prk-Jr wants to merge 5 commits into
feature/kv-geoipfrom
feature/480-cloudflare-spin-geo

Conversation

@prk-Jr

@prk-Jr prk-Jr commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Complete portable ctx.geo() coverage with Cloudflare request metadata and Spin lookup against an explicitly pinned KV dataset.
  • Admit one authenticated visitor-IP assertion on Spin, strip private headers before callbacks, and bound request-local preparation and lookup without retaining host handles.
  • Provide a separate operator loader that publishes the existing binary artifacts into Spin KV, verifies them, and stops its temporary loopback runtime.

Stacked on #454 (feature/kv-geoip), which already includes #502. The portable KV reader and Axum foundation are supplied by those parents.

Changes

Crate / File Change
edgezero-adapter-spin Manifest/environment selection, authenticated IP admission, pinned async lookup, request-local resources, private immutable geography, and native/WASM contracts
edgezero-core Spin geo configuration placement, bounded configuration namespace inspection, and authenticated-IP provenance
edgezero-adapter-axum Reject Spin-only credential settings on native geo selection
Cloudflare contracts and adapter guides Positive managed-entrypoint metadata coverage, country-only/absence behavior, and forged-header resistance
examples/geo-kv-prototype Expose the existing artifact/publication code to operator consumers without native backend features
examples/geo-spin-loader Separate binary dataset publisher, ephemeral credential, fixed diagnostic categories, finite deadlines, and tested child cleanup
CI and technical documentation Maintain loader checks, admit only their exact standalone unittest command, and document deployment, publication, cold-request cost, and trust boundaries

Spin defaults to off. KV selection requires a declared store, generation/hash pin, authenticated-header reader mode, and a Spin credential-variable name. A trusted proxy must replace and authenticate the original visitor IP; it does not need to supply geography. Both roots and the selected path are verified on each request. Geo errors remain application policy inputs and do not independently grant permission or select HTTP status. No automatic fallback is added.

Closes

Closes #480
Closes #486

Test plan

  • cargo test --workspace --all-targets (3,058 passed; nine ignored)
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo fmt --all -- --check
  • cargo check --workspace --all-targets --features "fastly cloudflare spin"
  • Fastly, Spin and Cloudflare WASM builds, strict lint and maintained suites (Fastly 362; Spin 39 contracts + 25 SDK; Cloudflare 142 library + 31 contracts)
  • examples/app-demo (68 tests + three WASM checks), 32 native feature combinations, 199 tooling tests, generated consumer, and isolated serial harness (679 passed; four ignored)
  • Docs lint, formatting and VitePress build
  • Native and WASM positive KV lookup, duplicate/spoof rejection, admission ordering, original head budgets, pending-work cancellation and aggregate timeout tests
  • Deliberately broken lookup, authentication and IP-removal controls fail their expected assertions; restored geo tests pass
  • Fresh Rust 1.98.1 / Spin 4.1 / SDK 8 runtime: 34 serving, 12 configuration, 13 fault/snapshot cases; fresh binary publication, identical replay and unchanged serving-store snapshots
  • Fresh Cloudflare Worker: 15 real workerd cases with source/artifact identity checks
  • Axum: actual manifest/environment-selected listener returns CloudFront US/CA without a Trusted Server boot profile
  • Operator publisher/loader tests, standalone strict lint and WASM compilation; five runner lifecycle tests including total timeout during a dripping response

Additional diagnostic: native cargo build --workspace --all-targets --all-features cannot link Fastly SDK host imports on ARM64. The same failure is reproduced on unchanged base 925fe019; the supported Fastly WASM suite passes all 362 tests using the prescribed CI runner.

  • Deploy-action tool-policy contract and ten exception-boundary regressions; modified shell/workflow lint

Checklist

  • Changes follow CLAUDE.md conventions
  • No Tokio dependencies added to core or adapter crates
  • Route parameters use {id} syntax
  • Application HTTP types come from edgezero_core
  • Serving store wiring uses the declared KvRegistry
  • New behavior has meaningful tests
  • No secrets, licensed datasets or credentials committed

Local synthetic runtime evidence does not qualify hosted proxy protection, external backend permissions/propagation, geography accuracy or production capacity. Spin SDK reads materialize values before core validates size; guest deadlines do not certify host-side cancellation. The request-local cache repeats manifest/root reads, so operators must qualify backend latency and capacity. Publication assumes one operator per generation; ordinary read-before-write is not a distributed lock.

@prk-Jr prk-Jr self-assigned this Nov 18, 2026
@prk-Jr prk-Jr changed the title Add authenticated Spin geo and verify Cloudflare context Complete Cloudflare geo and add pinned Spin KV lookup Nov 18, 2026
@prk-Jr
prk-Jr changed the base branch from spec/482-axum-geo-manifest-binding to feature/kv-geoip November 18, 2026 14:25

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant